Release 10.1A: OpenEdge Development:
Progress 4GL Reference

READ-XML( ) method

Reads an XML document into a ProDataSet, temp-table, or temp-table buffer object. You can read data, schema, or both.

Return type: LOGICAL

Applies to: Buffer object handle, ProDataSet object handle, Temp-table object handle

Syntax

READ-XML ( source-type, { file | memptr | handle | longchar }, read-mode, schema-location, override-default-mapping [, field-type-mapping [, verify-schema-mode ] ] )

source-type

A CHARACTER expression that specifies the source XML document type. Valid values are: “FILE”, “MEMPTR”, “HANDLE”, and “LONGCHAR”.

file

A CHARACTER expression that specifies the name of a file. You can specify an absolute pathname, a relative pathname (based on the current working directory), or a URL pathname. Valid URL protocols include FILE and HTTP (the HTTPS protocol is not supported). Progress verifies that the file exists and is accessible.

memptr

A MEMPTR variable that contains the XML document text in memory. The size of the MEMPTR variable must match the size of the XML document text.

handle

A WEB-CONTEXT system handle, X-document object handle, or X-noderef object handle.

For a WEB-CONTEXT system handle, the READ-XML( ) method reads an XML document from the WebSpeed transaction server. The method verifies that the XML document was posted to the WebSpeed transaction server (that is, the value of the IS-XML attribute for the handle is YES), and that Progress is running in a WebSpeed environment.

longchar

A LONGCHAR variable that contains the XML document text in memory.

read-mode

A CHARACTER expression that specifies the mode in which the READ-XML( ) method reads data from the XML document into a temp-table or ProDataSet member buffer. The expression must evaluate to “APPEND”, “EMPTY”, “MERGE”, or “REPLACE”. The default value is "MERGE".

Table 78 lists the READ-XML( ) method modes for reading data.

Table 78: READ-XML( ) method read modes 

When the mode is ...	The READ-XML( ) method ...
APPEND	Reads data from the XML document into the ProDataSet or temp-table object by adding new records to the existing records, without performing any record comparisons. If a record from the XML document exists in the object (that is, it results in a duplicate unique key conflict), the method generates an error message and returns FALSE.
EMPTY	Empties the contents of the ProDataSet or temp-table object before reading in data from the XML document.
MERGE	Reads data from the XML document into the ProDataSet or temp-table object by merging new records with existing records in the table. If a record from the XML document exists in the object (that is, it results in a duplicate unique key conflict), the method does not replace the existing record. If the record from the XML document does not exist in the object, the method creates a new record.
REPLACE	Reads data from the XML document into the ProDataSet or temp-table object by merging new records with existing records in the table. If the record from the XML document exists in the object (that is, it results in a duplicate unique key conflict), the method replaces the existing record with the new record. If the record from the XML document does not exist in the object, the method creates a new record.

schema-location

A CHARACTER expression that specifies the name of an external XML Schema file to use in creating or verifying the object’s schema when reading in the XML document. You can specify an absolute pathname, a relative pathname (based on the current working directory), or a URL pathname. Valid URL protocols include FILE and HTTP (the HTTPS protocol is not supported). Progress verifies that the file exists and is accessible. When specified, Progress ignores any schema defined or referenced in the source XML Document.

If you specify the empty string ("") or the Unknown value (?), Progress creates or verifies the object’s schema using any XML Schema defined or referenced in the XML document.

override-default-mapping

A LOGICAL expression where TRUE directs Progress to override the default mapping between XML Schema string and binary data types and Progress data types when creating a Progress temp-table schema from an XML Schema. The default value is FALSE.

The XML Schema string data type maps to the Progress CHARACTER data type by default, and the XML Schema base64Binary and hexBinary data types map to the Progress RAW data type by default. If you specify TRUE, the READ-XML( ) method creates a temp-table schema with CLOB and BLOB fields instead of CHARACTER and RAW fields.

If you specify the Unknown value (?), the method uses the default value of FALSE.

field-type-mapping

An optional CHARACTER expression that evaluates to a comma-separated list of field name, data type pairs using the following syntax:

field-name-1, data-type-1 [, field-name-n, data-type-n ] ...)

This option allows you to specify the Progress data type for a specific field from the XML Schema.

field-name

A CHARACTER expression that evaluates to the name of the specified field. For a ProDataSet object, you must qualify the field name with the buffer name from the XML Schema. That is, buffer-name.field-name.

data-type

A CHARACTER expression that evaluates to the data type of the specified field. The data type must be a valid Progress data type, and it must be compatible with the XML Schema type based on the Progress XML data type mapping rules. For example, any XML Schema type can be mapped to a Progress CHAR or CLOB, but an XML Schema dateTime can be mapped only to a Progress DATE, DATETIME or DATETIME-TZ.

If you specify the Unknown value (?), the method uses the default data type mapping. For more information about the Progress XML data type mapping rules, see OpenEdge Development: Programming Interfaces .

verify-schema-mode

An optional CHARACTER expression that specifies the mode in which the READ-XML( ) method verifies any XML Schema against existing Progress schema. The expression must evaluate to “IGNORE”, “LOOSE”, or “STRICT”. The default value is “LOOSE”.

Note: For a dynamic temp-table or ProDataSet member buffer that does not have Progress schema (that is, the object is in the CLEAR state), this option is ignored.

Table 79 lists the READ-XML( ) method schema verification modes.

Table 79: READ-XML( ) method schema verification modes

When the mode is ...	The READ-XML( ) method ...
IGNORE	Ignores any XML Schema specified in schema-location, or defined in the XML Document.
LOOSE	For temp-table objects: Matches temp-table columns by name. The data type and extent of the column in the XML Schema must match those for the matching column in the temp-table. Other field attributes in the XML Schema are ignored. The XML Schema may be a subset or superset of the temp-table schema. Any columns that are in the XML Schema but not in the temp-table are ignored. Any columns that are in the temp-table, but not in the XML Schema, are ignored. For ProDataSet objects: Matches temp-tables and columns by name. The data type and extent of the column in the XML Schema must match those for the matching column in the temp-table. Other field attributes in the XML Schema are ignored. Data relationships are matched by parent buffer and child buffer names. For every data relationship in the XML Schema that matches a data-relation in the ProDataSet, the field mapping between the parent and child buffers must match. The XML Schema may be a subset or superset of the ProDataSet schema. Any temp-tables, columns, or data-relations that are in the ProDataSet, but not in the XML Schema, are ignored. For a dynamic ProDataSet object, the method adds temp-tables and data-relations to the object when the temp-tables and data-relations are defined in the XML Schema, but are not members of the ProDataSet. Fields are not added to existing temp-tables. For a static ProDataSet object, any temp-tables or data-relations that are in the XML Schema, but not in the ProDataSet, are ignored.
STRICT	For temp-table objects: Matches temp-table columns by name. The data type and extent of the column in the XML Schema must match those for the matching column in the temp-table. Other field attributes in the XML Schema are ignored. The XML Schema must define a field for every temp-table field, and there can be no extra fields in the XML Schema that are not in the temp-table schema. For ProDataSet objects: Matches temp-tables and columns by name. There must be a temp-table defined in the XML Schema for each table of the ProDataSet. There can be no tables defined in the XML Schema that are not in the ProDataSet schema. There must be field defined in the XML Schema for each field in the temp-table, with the same data type and extent, and there can be no fields defined in the XML Schema that are not in the temp-table schema. There must also be a data relationship defined in the XML Schema for every data-relation in the ProDataSet, and there can be no data relationships defined in the XML Schema that are not defined in the ProDataSet. The field mapping between the parent and child buffers must match.

If you specify the Unknown value (?), the method uses the default value of LOOSE.

If the XML Schema verification fails, the method generates an error message indicating the XML Schema element that caused the failure and returns FALSE.

Examples

The following code example creates a dynamic ProDataSet object from an empty ProDataSet handle, creates the object’s schema from the specified XML Schema file, and populates the temp-tables with records from the specified XML document:

DEFINE VARIABLE cSourceType AS CHARACTER NO-UNDO. DEFINE VARIABLE cReadMode AS CHARACTER NO-UNDO. DEFINE VARIABLE lOverrideDefaultMapping AS LOGICAL NO-UNDO. DEFINE VARIABLE cFile AS CHARACTER NO-UNDO. DEFINE VARIABLE cEncoding AS CHARACTER NO-UNDO. DEFINE VARIABLE cSchemaLocation AS CHARACTER NO-UNDO. DEFINE VARIABLE cFieldTypeMapping AS CHARACTER NO-UNDO. DEFINE VARIABLE cVerifySchemaMode AS CHARACTER NO-UNDO. DEFINE VARIABLE retOK AS LOGICAL NO-UNDO. DEFINE VARIABLE hDSet AS HANDLE NO-UNDO. CREATE DATASET hDSet. ASSIGN cSourceType = "file" cFile = "dset.xml" cReadMode = "empty" cSchemaLocation = "cust-ord-inv.xsd" lOverrideDefaultMapping = ? cFieldTypeMapping = ? cVerifySchemaMode = ?. retOK = hDSet:READ-XML(cSourceType, cFile, cReadMode, cSchemaLocation, lOverrideDefaultMapping, cFieldTypeMapping, cVerifySchemaMode).

The following code example creates a dynamic temp-table object from an empty temp-table handle, creates the object’s schema from the specified XML Schema file, and populates the temp-table with records from the specified XML document:

DEFINE VARIABLE cSourceType AS CHARACTER NO-UNDO. DEFINE VARIABLE cReadMode AS CHARACTER NO-UNDO. DEFINE VARIABLE lOverrideDefaultMapping AS LOGICAL NO-UNDO. DEFINE VARIABLE cFile AS CHARACTER NO-UNDO. DEFINE VARIABLE cEncoding AS CHARACTER NO-UNDO. DEFINE VARIABLE cSchemaLocation AS CHARACTER NO-UNDO. DEFINE VARIABLE cFieldTypeMapping AS CHARACTER NO-UNDO. DEFINE VARIABLE cVerifySchemaMode AS CHARACTER NO-UNDO. DEFINE VARIABLE retOK AS LOGICAL NO-UNDO. DEFINE VARIABLE httCust AS HANDLE NO-UNDO. CREATE TEMP-TABLE httCust. ASSIGN cSourceType = "file" cFile = "ttcust.xml" cReadMode = "empty" cSchemaLocation = "ttcust.xsd" lOverrideDefaultMapping = ? cFieldTypeMapping = ? cVerifySchemaMode = ?. retOK = httCust:READ-XML(cSourceType, cFile, cReadMode, cSchemaLocation, lOverrideDefaultMapping, cFieldTypeMapping, cVerifySchemaMode).

Notes

If the ProDataSet or temp-table object does not have a schema (that is, the object is dynamic and in the CLEAR state), Progress creates the schema from either the XML Schema file specified in schema-location, or the XML Schema defined or referenced in the XML document. If a dynamic temp-table is not in the PREPARED or CLEAR state, the method generates an error and returns FALSE.

If the ProDataSet or temp-table object already has a schema (that is, the object is static, or the temp-tables are in the PREPARED state), Progress verifies any XML Schema specified by schema-location, or defined or referenced in the XML document, against the object’s schema, unless the verify-schema-mode is “IGNORE”.

If Progress cannot identify any XML Schema for the ProDataSet or temp-table object, (that is, schema-location is the empty string ("") or the Unknown value (?) and the XML document does not define or reference a schema, Progress infers the schema from the data in the XML document.

For more information about creating schema from XML Schema, verifying XML Schema, or inferring schema from XML document text, see OpenEdge Development: Programming Interfaces .

The XML document can also contain before-image table data associated with a ProDataSet object. If the XML document data is in the Microsoft DiffGram format, the method reads the before-image data as well. In this case, if the ProDataSet or temp-table object is static and it does not have a before-image table defined, the method generates an error and returns FALSE. If the ProDataSet or temp-table object is dynamic, the method creates the before-image table automatically.
Note: During the read operation, Progress does not respond to ProDataSet events, and it does not track changes to the data in the ProDataSet or temp-table object (that is, it does not update the before-image tables) unless the XML document data is in the Microsoft DiffGram format.
You cannot read an XML document into a database buffer.

See also

IS-XML attribute, READ-XMLSCHEMA( ) method, WEB-CONTEXT system handle, WRITE-XML( ) method, WRITE-XMLSCHEMA( ) method, X-document object handle, X-noderef object handle